PATHHardware Documentation > USB Devices > Mac OS USB DDK API Reference

The USBPB Parameter Block

The majority of calls to the USL are made with a parameter block of type USBPB. The USBPB parameter block contains all the necessary parameters to facilitate host communication with the device interface or device interface communication with the USB. The parameter block also includes a pointer to a callback completion routine for support of asynchronous calls.

There are currently two version of the USBPB parameter block, the version 1.0 parameter block ( kUSBCurrentPBVersion ), defined in this section, and the version 1.1 parameter block ( kUSBIsocPBVersion ), defined in Changes In Mac OS USB Version 1.1, that supports isochronous transfers. Version 1.1 of the Mac OS USB software accepts function calls made with both parameter blocks. For information about converting existing code to use the 1.1 USBPB, see Code Changes Required To Support The Version 1.1 USBPB .

Parameters for the USBPB parameter block that are not specified as required in the USL function descriptions are ignored by the USL. Parameters that are not specified as output values are not altered, except for the Reserved, usbWValue, and usbWIndex fields.

The types associated with the version 1.0 USBPB parameter block structure and the USBPB structure are defined as follows:

The version 1.0 USBPB parameter block is defined as:

    void* qlink;
    UInt16 qType;
    UInt16 pbLength;                /* Length of parameter block */
    UInt16 pbVersion;               /* Parameter block version number */
    UInt16 reserved1;               /* Reserved */
    UInt32 reserved2;               /* Reserved */
    OSStatus usbStatus;             /* Completion status of the call */
    USBCompletion usbCompletion;    /* Completion routine */
    UInt32 usbRefcon;               /* For use by the completion routine */
    USBReference usbReference;      /* Device, pipe, interface, endpoint */
                                   /* reference as appropriate */
    void* usbBuffer;                /* Pointer to the data to be sent */
                                   /* to or received from the device */
    USBCount usbReqCount;           /* Length of usbBuffer */
    USBCount usbActCount;           /* Number of bytes sent or received */
    USBFlags usbFlags;              /* Miscellaneous flags */
    UInt8 usbBMRequestType;         /* For control transactions, */
                                  /* the bmRequestType field */
    UInt8 usbBRequest;              /* Specific control request */
    USBRqValue usbWValue;           /* For control transactions, the */
                                   /* Value field of the setup packet */
    USBRqIndex usbWIndex;           /* For control transactions, the */
                                  /* Index field of the setup packet */
    UInt16 reserved4;               /* Reserved */
    UInt32 usbFrame;                /* Reserved for future use */
    UInt8 usbClassType;            /* Class for interfaces, */
                                   /* transfer type for endpoints */
    UInt8 usbSubclass;              /* Subclass for interfaces */
    UInt8 usbProtocol;              /* Protocol for interfaces */
    UInt8 usbOther;                 /* General-purpose value */
    UInt32 reserved6;               /* Reserved */
    UInt16 reserved7;               /* Reserved */
    UInt16 reserved8;               /* Reserved */

    }USBPB;

During asynchronous calls, before the callback, no fields in the parameter block are valid other than the usbRefcon field. The usbRefcon field is never altered and is free for use by class drivers.

The USBPB parameter block has to be at least the minimum size. The size can be extended; the pbLength field should contain the extended size.

The current version of the parameter block is represented as a binary-coded decimal number. For version 1.0 it is of the form 0x010. It is subject to change at any time. Use the constant kUSBCurrentPBVersion to make sure you have the version of the parameter block described by the latest revision of this document. The isochronous variant of the parameter block is version 1.1 ( kUSBIsocPBVersion ). The version 1.1 parameter block is defined in Changes In Mac OS USB Version 1.1 .

The values passed in the usbBMRequestType field require a specific format, which can be derived by using the USBMakeBMRequestType function .

Previous | Back Up One Level | Next |